The primary method for launching Pedagogica is through WebStart and JNLP (Java Network Launch Protocol) files. In this page we will give a brief description of what happens when an activity is run and then we will list how to set up and run various configurations.

Except for running in a Java IDE (such as Eclipse), all Pedagogica 2.0 activities are launched from a JNLP file. This JNLP file can exist on a local or network file system, or on some web server. On the local or network file system, you can launch the activity by double-clicking the JNLP file if two conditions are fulfilled:

1. The required version of Java is installed on the local machine
2. The .jnlp extension is registered with the WebStart client application on the local machine.

Usually step 2 is done when Java is installed, but there may be reasons why this didn't happen. If so, check with your local system administrator.

Also JNLP files can launch from links on a web page. For this to happen automatically, .jnlp files must be resistered for such use with the browser you are using. Sometimes this just works, but sometimes it requires user or administrator modification of the browser configuration or prefences. Again, none of the above will work if the apporpriate version of Java is not installed (as of the writing of this document, that version is J2SE 1.4.2).

Running an Activity

Before we go more in-depth with the discussion of running an activity, we first need to introduce the DomainClassLoader and and how it uses a codebase. The DomainClassLoader is both a dynamic class loader (based on the Java URLClassLoader) and a system bootstrap mechanism for the Pedagogica 2.0 system and running Pedagogica activities. The codebase is the root URL relative to which ALL resources used by the Pedagogica system and the activities can be accessed. This codebase URL is provided in the JNLP file by the jnlp xml element attribute of the same name (following sample taken from a subsequent example below that):

<jnlp codebase="http://wise25.concord.org/workspaces/wise25/Release">

The CachingClassLoader retrieves the value of this codebase attribute by calling into the WebStart runtime library (via reflection). When the CachingClassLoader is given a path such as Pedagogica/lib/pedagogica.jar, it then locates that resource relative to the codebase. When it loads a jar file resource, it looks at the Class-Path property in the manifest for a list of relative paths. It then adds each of those paths resolved by the codebase, making the assumption that the list represents the jar files upon which the current jar file is dependent.

Now, let us now describe what happens when a authorable Pedagogica activity is launched.

1. The WebStart application opens (or downloads and opens, in the case of the Web) the JNLP file and parses the JNLP text.
2. WebsStart is instructed to download the signed jar file Loader/lib/loader.jar.
3. The main method on the class LauncherView invoked with the arguments provided in the JNLP file.
4. LauncherView then takes control over from WebStart and launches itself in a new JVM (new process running the Java Virtual Machine) and passes the remaining launch arguments.
5. The new instance of DomainClassLoader (in the new JVM) then invokes the main method of RunActivity with arguments telling it which activity to run (and where it is), and the user context for saving and restoring state.
6. A rainbow status bar appears (with a Cancel button) to inform of download and launching status.
7. The activity appears on the user's screen.

Below is a sample of JNLP text that will run the Genetics Generic Activity. This sample was generated by a tool (also a Pedagogica activity) that took the web location of the activity jar file and created the necessary resource and argument XML codes for the target JNLP file.

<?xml version="1.0" encoding="UTF-8"?> 
<jnlp codebase="http://wise25.concord.org/workspaces/wise25/Release/">
	<information>
		<title>Genetics Generic Activity</title>
		<vendor>The Concord Consortium</vendor>
		<icon href="images/cc-icon.jpg"/>
		<offline-allowed/>
	</information>
	<resources>
		<j2se version="1.4+"/>
		<jar href="Pedagogica/lib/pedagogica.jar"></jar>
		<jar href="Framework/lib/framework.jar"></jar>
		<jar href="Swing/lib/ccswing.jar"></jar>
		<jar href="FrameworkView/lib/frameworkview.jar"></jar>
		<jar href="Loader/lib/loader.jar"></jar>
		<jar href="thirdparty/js-1.5R4.1.jar"></jar>
		<jar href="Assessment/lib/assessment.jar"></jar>
		<jar href="Biologica/lib/biologica.jar"></jar>
	</resources>
	<application-desc main-class="org.concord.pedagogica.ui.RunActivity">
		<argument>-start</argument>
		<argument>Activity/Biology/Genetics/Genetics.jar</argument>
	</application-desc>
	<security>
    		<all-permissions/>
	</security>
</jnlp>

We refer the reader to Sun Microsystem's WebStart Developer Documentation for the particulars on the JNLP text. Here we will focus primarily on the name and purpose of the arguments passed to Java classes we are launching.

There are two sets of arguments in the above JNLP example, DomainClassLoader arguments and RunActivity arguments. Let's examine the the DomainClassLoader arguments first:

• launch - Determines whether or not DomainClassLoader will launch a new JVM. This argument needs to be present unless ALL of the jar file used by the client are signed.
• update - DomainClassLoader automatically caches any non-file URL into a local file. The presence of this argument tells DomainClassLoader to also automatically check for new versions of those files at the addresss specified by the URLs, and automatically download them into the cache. This argument is meant to be controlled by the server when it creates the JNLP file, to guarantee that the clients get updated versions of the files.
• paths - This is the keyword part of a keyword-value pair. The value part is the codebase relative class path that is needed to run the the main class specified after it. In the case of Pedagogica activities, the value part is always what is specified in the above example (Pedagogica/lib/pedagogica.jar).
• the main class - For Pedagogica activitgies, this will be RunActivity. This is the Pedagogica class that collects the remaining arguments and runs the specfied activity.

Now we can move on to the RunActivity arguments. First, be aware that except for the argument that specifies the activity, all RunActivity arguments take one of two forms:

1. -name for flag arguments that do not require a value
2. name=value for arguments that do require a value

In the above example there are only the activity specification argument and arguments of type 1. The other type of argument will be shown in the section describing the use of Pedagogica in WISE 2.5. Arguments of type 1 are:

• -author specifies that the activity is to run in authoring mode, which means it can be customized by the user (author).
• -local indicates that any state saved will be stored in a local file created by the Pedagogica system. By default, this will be placed in the same cache directory as the cached activity file, and with the same name with the exension ".save.jar" added. This argument is primarily used for development and testing purposes.

Referring again to the above example JNLP file, it should be noted that it represents a test file that uses a web codebase. Another way of running the activity is by making the codebase refer to a local directory, rather than one on the web. Below is an example of such a JNLP file:

<?xml version="1.0" encoding="UTF-8"?>
<jnlp codebase="file:/C:/Work/Projects">
    <information>
        <title>Genetics Generic Activity</title>
        <vendor>The Concord Consortium</vendor>
        <icon href="genetics-icon.gif"/>
        <offline-allowed/>
    </information>
    <resources>
        <j2se version="1.4+"/>
        <jar href="Domain/lib/domain.jar"/>
    </resources>
    <application-desc main-class="org.concord.domain.DomainClassLoader">
        <argument>launch</argument>
        <argument>update</argument>
        <argument>paths</argument>
        <argument>Pedagogica/lib/pedagogica.jar</argument>
        <argument>org.concord.pedagogica.ui.RunActivity</argument>
        <argument>Activity/Biology/Genetics/Genetics.jar</argument>
        <argument>-author</argument>
        <argument>-local</argument>
    </application-desc>
    <security>
        <all-permissions>
    </security>
</jnlp>

Notice that this example is identical to the previous one except for the codebase attribute in the jnlp element. The codebase in this case refers to an absolute path (via a file URL) to a local directory on a Windows platform. This will work just like the first example, as long as ALL of the resources (jar files, etc.) needed by the activity are available under that directory on the local machine. One way to get all the resources, is to run it from the web first, and then move the Projects folder in the cache directory to some other place, and point the local codebase to that place. This configuration is better for testing and developing because it is much faster due to the fact that it is not going to the network all the time.

Running an Activity in WISE 2.5

WISE / Pedagogica integration in WISE 2.5 requires that the Pedagogica step have an authoring mode with state that can be saved. When the step is then subsequently run in student mode, that saved state is restored (from somewhere). Since a student (or author) can be runnig from any machine at any time, it is obvious that the state cannot be saved on individual machines. In this case, the state must be saved on a server machine. Furthermore, there must be enough information when the step is run to know which activity of which project and which authoring state of which (teacher, author) mus be restored. This additional information is provided as extra arguments in the JNLP file that is generated during the interaction with the WISE server and the Pedagogica database server.

There are two types of JNLP files generated during the WISE 2.5 Pedagogica step process. The first type is generated with an arguments specifying authoring mode turned on, and upload and download URLs for saving and restoring state. The other type is for student mode, where authoring is turned off, and only a download URL is required for restoring the authored state. Eventually the student mode JNLP can also provide a different upload URL for student state, if that is desired for Pedagogica steps, but that is not yet supported.

Notes:

Whether or not an new JVM is started actually depends on the presence of the launch argument in the JNLP file. If the launch argument is not provided, then DomainClassLoader will attempt to run everything in the original JVM. However, if this is done, then all of the other jar files downloaded by DomainClassLoader must also be signed with the same certificate as domain.jar. If they are not all signed, then a security exception will be thrown when one of their contained classes is loaded.

If update is set, then there are performance implications for the client using DomainClassLoader, because every file that has been cached, will be checked on the server of the original URL. This means a connection will be opened, and the date/time of the file on the server will be compared to the date/time of the corresponding cache file. If the the server file date/time is more recent than the cache file date/time, then the new server version will be downloaded to replace the currently cached version. There will optimizations in future releases of Pedagogica 2.0 that will fix many of these performance issues (usually in ways similar to how they were addressed in Pedagogica 1.0).